/*++****************************************************************************
*
*	Name: lib_usb_cdc.h
*
*	Description: This library is a wrapper for the USB Communication Device Class. 
*				 The USB stack is provided by Microchip. 
*
*	How to use:
*
*		Open USB port with "lib_usb_cdc_open()".
*		Call "lib_usb_cdc_process_main()" in your main application loop.
*		Use "lib_usb_cdc_read" and "lib_usb_cdc_write" to read and write.
*
*	Supported Comilers:
*		
*		MPLAB C18
*		MPLAB C32
*
*	Revision History:
*	Date	Who	Comments	
*	------	---	---------------------------------------------------------------
*	110521	DHT	Created
****************************************************************************--*/

#ifndef LIB_USB_CDC_H
#define LIB_USB_CDC_H


/**** error codes ****/

#define LIB_USB_CDC_SUCCESS				0

#ifndef ROM
#define ROM	rom
#endif


/*********************************************************************
 * Function:        INT16 lib_usb_cdc_open()
 *
 * Overview:		Init USB module for USB CDC device
 *
 * PreCondition:    None
 *
 * Input:			None
 *
 * Output:          success = 0
 *					error codes can be found in lib_usb_cdc.h
 *
 * Note:            This function blocks and waits for the usb to 
 *					finish configuring before returning. This can 
 *					take up to several seconds.
 ********************************************************************/
INT16 lib_usb_cdc_open(void);


/*********************************************************************
 * Function:        INT16 lib_usb_cdc_close()
 *
 * Overview:		Detach USB device from host
 *
 * PreCondition:    None
 *
 * Input:			None
 *
 * Output:          success = 0
 *					error codes can be found in lib_usb_cdc.h
 *
 * Note:            Not yet tested!!!
 ********************************************************************/
INT16 lib_usb_cdc_close(void);


/*********************************************************************
 * Function:        INT16 lib_usb_cdc_read(UINT8 *buffer, UINT8 size)
 *
 * Overview:		Read from USB port
 *
 * PreCondition:    lib_usb_cdc_open()
 *
 * Input:			buffer - byte array to store bytes read
 *					size - size of buffer variable
 *
 * Output:          Number of bytes read
 *
 * Note:            A maximum of 64 bytes can be read each time
 ********************************************************************/
INT16 lib_usb_cdc_read(UINT8 *buffer, UINT8 size);


/*********************************************************************
 * Function:        INT16 lib_usb_cdc_write(UINT8 *buffer, UINT8 size)
 *
 * Overview:		Write bytes to the USB port
 *
 * PreCondition:    lib_usb_cdc_open()
 *
 * Input:			buffer - array of bytes to write
 *					size - size of buffer variable
 *
 * Output:          Number of bytes written
 *
 * Note:            A maximum of 255 bytes can be written at a time
 ********************************************************************/
INT16 lib_usb_cdc_write(UINT8 *buffer, UINT8 size);


/*********************************************************************
 * Function:        INT16 lib_usb_cdc_write_blocked(UINT8 *buffer, UINT8 size)
 *
 * Overview:		Write bytes to the USB port and block until all bytes
 *					are sent.
 *
 * PreCondition:    lib_usb_cdc_open()
 *
 * Input:			buffer - array of bytes to write
 *					size - size of buffer variable
 *
 * Output:          Number of bytes written
 *
 * Note:            A maximum of 255 bytes can be written at a time.
 *					This is a blocked io. 
 ********************************************************************/
INT16 lib_usb_cdc_write_blocked(UINT8 *buffer, UINT8 size);


/*********************************************************************
 * Function:        INT16 lib_usb_cdc_printf(const ROM char *fmt, ...)
 *
 * Overview:		Output string to usb with printf 
 *
 * PreCondition:    lib_usb_cdc_open()
 *
 * Input:			fmt - format of string
 *					... - variable list of variables
 *
 * Output:          Number of bytes written
 *
 * Note:            A maximum of 255 bytes can be written at a time
 ********************************************************************/
#if defined(__18CXX)
INT16 lib_usb_cdc_printf(const ROM char *fmt, ...);
#else
INT16 lib_usb_cdc_printf(const char *fmt, ...);
#endif


/*********************************************************************
 * Function:        INT16 lib_usb_cdc_printf_blocked(const ROM char *fmt, ...)
 *
 * Overview:		Output string to usb with printf and wait until message
 *					successfully sends.
 *
 * PreCondition:    lib_usb_cdc_open()
 *
 * Input:			fmt - format of string
 *					... - variable list of variables
 *
 * Output:          Number of bytes written
 *
 * Note:            A maximum of 255 bytes can be written at a time.
 *					This is a blocked io. Use the regular lib_usb_cdc_printf
 *					if you want non-blocking io.
 ********************************************************************/
#if defined(__18CXX)
INT16 lib_usb_cdc_printf_blocked(const ROM char *fmt, ...);
#else
INT16 lib_usb_cdc_printf_blocked(const char *fmt, ...);
#endif

/*********************************************************************
 * Function:        INT16 lib_usb_cdc_process_main()
 *
 * Overview:		Service USB Stack
 *
 * PreCondition:    lib_usb_cdc_open()
 *
 * Input:			None
 *
 * Output:          None
 *
 * Note:            Must call this function in your main loop
 ********************************************************************/
void lib_usb_cdc_process_main(void);


// remind user to call usb interrupt routine in interrupt handler if using
// interrupt based usb stack. only needed for the pic18's because the pic32's
// have a seperate interrupt vector for usb which is handled by the USB stack.
#if defined(__18CXX) && defined(USB_INTERRUPT)
#warning Please call lib_usb_cdc_process_interrupt() in High Priority Interrupt
#endif
	 
/*********************************************************************
 * Function:        void lib_usb_cdc_process_interrupt()
 *
 * Overview:		Services USB interrupt 
 *
 * PreCondition:    None
 *
 * Input:			None
 *
 * Output:          None
 *
 * Note:            Only need to call this in C18 code. Not needed
 *					for C32 code.
 ********************************************************************/
void lib_usb_cdc_process_interrupt(void);

#endif

